Document that deploy_component waits for restart: true and reports restart_completed - #638

Code Review

This pull request adds documentation for the restart parameter under the Deployment Operations section in reference/operations-api/operations.md, detailing the behavior of `

Approving. I verified every claim in the diff against harper origin/main and they all hold:

• restart: true waits before responding — components/operations.js:809-811 awaits awaitRestart(...)
• Progress-based rather than fixed-timeout — awaitRestart.ts's own header says exactly that
• The three give-up conditions map to real RestartOutcome fields (stalled, the ceiling, workersKeptOnOldCode/replacementsNotStarted)
• The outcome is logged — logRestartOutcome(restart, ...) at :814
• A failed restart genuinely does not fail the deploy — the result is not thrown on, and execution proceeds to the success message
• "rolling" starts a replicated: true restart_service job and returns restartJobId (:818-826)
• drop_component waits the same way — second awaitRestart call site at :1343
• restart_completed is correctly absent: zero occurrences anywhere in harper

On the badge: components/awaitRestart.ts does not exist at v5.2.6, v5.2.7 or v5.2.8, so the change is merged but unreleased and v5.3.0 is defensible. (Checked by testing for the file at each tag rather than --contains, and dereferencing with ^{} — git ls-remote refs/tags/v5.2.8 reports the annotated tag object 85fbf969e, not the commit 23264cebb, which is an easy way to conclude a phantom divergence.)

Two non-blocking notes, neither worth holding this up for.

The two bounds are exported constants but not documented. awaitRestart.ts exports RESTART_IDLE_TIMEOUT_MS = 60_000 and RESTART_WAIT_CEILING_MS = 600_000. The text says the response "can take as long as the install plus the restart — tens of seconds on a slow install with many worker threads" and advises that a caller with a short request timeout should use rolling instead. That advice is right, but "tens of seconds" anchors an order of magnitude below the real ten-minute ceiling, and "short" is undefined when there is an exact number available. A CI author sizing a client timeout from this could pick 60s and get cut off partway through a legitimately slow restart — the same failure this change prevents, just relocated from the server to the client. Worth stating both numbers in a follow-up.

The title is stale. It still says "and reports restart_completed", which the body correctly explains was dropped from #2341 and therefore from here. I am correcting it on the squash so it does not land in the commit message.

I also updated the branch before merging — it was 32 commits behind, and operations.md had moved in five of them, so CI had passed against a stale base.

_{sent with Claude Opus 5}